Release 10.1A: OpenEdge Development:
Programming Interfaces

Property and method syntax

The syntax to access properties and methods is similar to the syntax to access widget attributes and methods. However, where widget references use widget handles, COM object references use component handles. Component handles support an extended syntax that allows you to:

Chain component handle references to properties and methods.
Specify indexes on properties.
Specify mappings between Progress data types and COM data types for method output parameters and property settings.
Specify additional options for method parameters and return values.

The following syntax diagrams describe the syntax for method and property references. These diagrams are equivalent to the syntax presented in the OpenEdge Development: Progress 4GL Reference , but describe method and property references in a more top-down fashion. (See the information on attributes and methods in the OpenEdge Development: Progress 4GL Reference .)

Note: All COM object errors are translated to Progress errors. To suppress any error messages generated by a COM object method or property reference, you can specify the NO-ERROR option in any statement that includes the method or property reference.

Method reference

This is the syntax for a COM object method reference:

Syntax

[ NO-RETURN-VALUE ] COMhdl-expression:Method-Name-Reference

NO-RETURN-VALUE

Required for some methods that do not have a return value.

NO-RETURN-VALUE prevents Progress from expecting a possible return value. This option is appropriate only if the method does not have a return value. Whether a method call requires this option depends on the COM object. Some COM objects require that the caller knows there is no return value. In this case, you must specify the option. Many more robust COM objects do not require this option.

If the method requires NO-RETURN-VALUE and you don’t specify it, the COM object generally returns an error. For example, Word for Windows 95 Version 7.0 returns an error similar to “Non-function called as function.”

Note: If the method has a return value, you must not invoke it in a statement with the NO-RETURN-VALUE option. In this case, ignore the return value without specifying this option, as in the second call to the SetDate() method.

COMhdl-expression

An expression that returns a component handle to the COM object that owns the method specified by Method-Name-Reference.

Method-Name-Reference

Specifies a single COM object method that might return a value.

Property reference

This is the syntax for a COM object property reference:

Syntax

COMhdl-expression:Property-Name-Reference

COMhdl-expression

An expression that returns a component handle to the COM object that owns the property specified by Property-Name-Reference.

Property-Name-Reference

Specifies a single COM object property.

Component handle expression

Every method or property reference must begin with a component handle expression that returns a component handle value. This is the syntax to specify a component handle expression:

Syntax

COMhandle [ : Method-Name-Reference | Property-Name-Reference ] ...

COMhandle

A component handle variable. (Note that the first element in a component handle expression must be a COM-HANDLE variable.)

Method-Name-Reference

Specifies a single COM object method or property that returns a component handle value. A component handle expression can chain as many method and property references as required to return the handle to a particular COM object.

Property-Name-Reference

Specifies a single COM object method or property that returns a component handle value. A component handle expression can chain as many method and property references as required to return the handle to a particular COM object.

Note: For the most efficient dispatch of multiple references to a particular COM object, assign the initial component handle expression for the COM object to a COM-HANDLE variable. Each reference to a given component handle expression incurs additional run-time overhead for each method or property referenced in the expression.

Method name reference

This is the syntax to specify a single COM object method:

Syntax

Method-Name ( { [ OUTPUT | INPUT-OUTPUT ] expression [ AS datatype ] [ BY-POINTER | BY-VARIANT-POINTER ] | null-parameter } [ , [ OUTPUT | INPUT-OUTPUT ] expression [ AS datatype ] [ BY-POINTER | BY-VARIANT-POINTER ] | null-parameter ] ... )

Method-name

The name of the COM object method. This name is not case sensitive. But by convention, OpenEdge documentation shows COM object method names in mixed case.

expression

Any valid Progress expression that you can pass as a parameter to the method.

datatype

One of several data-type specifiers that the associated parameter might require. For more information on datatype, see Table 14–2. The remaining keyword options specify additional type and mode information for each parameter. The COM object defines the data types and numbers of parameters for a method.

null-parameter

Any amount of white space, indicating an optional parameter that you choose to omit. You can also pass variable numbers of parameters if the method supports it. For more information on specifying method parameter options, see the "Specifying options for properties and method parameters" section.

You can invoke a method in two ways:

Include the appropriate method reference as part of a Progress expression. This expression can be on the right side of an assignment statement or in any other statement that accepts the expression. Methods invoked with this technique must return a value. For example, if YearDay() is a method that returns the number of days from the first of the year to a specified date, it can appear in the following bolded expressions:

DEFINE VARIABLE myObject AS COM-HANDLE DEFINE VARIABLE day-of-year AS INTEGER. /* ... Access COM object as myObject ... */ day-of-year = myObject:YearDay("05/01/1997"). DISPLAY myObject:YearDay(TODAY) " days have passed this year.".

Specify the appropriate method reference as a statement, ignoring any return value. Methods invoked as a statement might require the NO-RETURN-VALUE option (shown previously in the Method Reference syntax). If SetDate( ) allows you to set a date for a COM object, you might invoke it in the following bolded statements:

DEFINE VARIABLE myObject AS COM-HANDLE DEFINE VARIABLE day-of-year AS INTEGER. /* ... Access COM object as myObject ... */ NO-RETURN-VALUE myObject:SetDate(1995,5,1). /* Set "May 1, 1995" */ myObject:SetDate(,5,1). /* Set "May 1" of current year */

Property name reference

This is the syntax to specify a single COM object property:

Syntax

Property-Name [ ( index [ , index ] ... ) ] [ AS datatype-specifier ]

Property-Name

The name of the COM object property. This name is not case sensitive. But by convention, OpenEdge documentation shows COM object property names in mixed case.

index

Any expression that legally indexes the property and for the required number of dimensions. If necessary and if possible, Progress converts the data type of index to the COM data type expected by the property. Essentially, the syntax is the same as for a method reference with input parameters.

datatype-specifier

One of several data-type specifiers that the associated property might require when you set its value. For more information on datatype, see Table 14–2. For more information on specifying the AS datatype option and data type conversion for properties, see the "Specifying options for properties and method parameters" section.

You can reference a property in two ways:

Read the property by specifying the appropriate property reference as part of a Progress expression. This expression can be on the right side of an assignment statement or in any other statement that accepts the expression, as in the following bolded expressions:

DEFINE VARIABLE myObject AS COM-HANDLE DEFINE VARIABLE degF AS INTEGER. /* ... Access COM object as myObject ... */ degF = myObject:TempFahrenheit. DISPLAY "The current temperature is " myObject:TempFahrenheit " degF.".

Write (set) the property by specifying the appropriate property reference on the left side of an assignment statement, as in the following bolded property references:

DEFINE VARIABLE myObject AS COM-HANDLE /* ... Access initial COM object as myObject ... */ myObject:SavingsAcount("1000-24-369"):AccountName(1) = "John". myObject:SavingsAcount("1000-24-369"):AccountName(2) = "Doe".

Note the use of a chained component handle expression to reference a savings account object. AccountName is an indexed property of the SavingsAccount object that specifies a first and last name for the account.

Data-type specifier

Progress supports a protocol to provide default mappings between native COM object method parameter and property values and the corresponding Progress data values. This mapping protocol supports many COM data types. You can override the default mapping by using a type specifier, as shown in Table 14–2. For more information on mapping data types shown in Table 14–2, see Appendix A "COM Object Data Type Mapping."

Table 14–2: Data-type specifiers for COM object methods and properties 

Data-type specifier to override the default mapping	Progress data type
CURRENCY	DECIMAL
ERROR-CODE	INTEGER
IUNKNOWN	COM-HANDLE
FLOAT	DECIMAL
SHORT	INTEGER
UNSIGNED-BYTE	INTEGER

Each of these data-type specifiers represents one of the base COM data types available for a method parameter or property. Each Progress data type represents the typical Progress data type that corresponds to the specified COM data type.

Data-type specifier options are necessary only for some method input parameters and property settings. Whether or not you must specify the AS datatype or any of the other type options (BY-POINTER or BY-VARIANT-POINTER) depends on the COM object method or property and the implementation of the COM object. You can also specify how a method parameter of any data type is passed using the mode options OUTPUT or INPUT-OUTPUT. Whether you use a mode option depends (in part) on how you plan to use the method parameter in your application. For more information on using data-type specifiers and mode options, see the "Specifying options for properties and method parameters" section, and Appendix A "COM Object Data Type Mapping."